Skip to content

Taint-combination engine: first-class hardening (v0.2.1)#13

Merged
tachyon-beep merged 5 commits into
mainfrom
taint-combination-hardening
May 31, 2026
Merged

Taint-combination engine: first-class hardening (v0.2.1)#13
tachyon-beep merged 5 commits into
mainfrom
taint-combination-hardening

Conversation

@tachyon-beep

Copy link
Copy Markdown
Collaborator

Summary

First-class hardening of the taint-combination engine, following the 2026-05-31 taint-combination soundness & precision audit. The audit found the engine correct (0 live FP, 0 live FN, oracle battery 30/30, self-host clean) — this work does not fix a broken engine; it makes the reachable-set correctness enforced rather than incidental, retires vestigial dead code, and closes the documentation gaps.

Epic [wardline-2b138b3662] — 9 of 10 children (the compute_return_callee explain-surface feature was deliberately deferred).

Architectural decision: RETAIN the 8-state lattice + taint_join as the documented contrast operator (rather than collapse to 5 states). Recorded in docs/decisions/2026-05-31-wardline-taint-lattice-retain.md. A parser guard (F5) makes the trio's unreachability enforced rather than relying on deletion.

Changes

Finding What
F5 Gate the two ungated TaintState parsers. stdlib_taint accepts {ASSURED, GUARDED, EXTERNAL_RAW, UNKNOWN_RAW}; summary_cache accepts the full reachable set incl. INTEGRAL. Both reject the never-produced trio (MIXED_RAW, UNKNOWN_GUARDED, UNKNOWN_ASSURED). No behaviour change for valid inputs.
F2 Remove the proven-dead unresolved-clamp in the SCC round (subsumed by the preceding floor) + its orphaned unresolved_counts param. Behaviour-preserving.
F3 RETAIN marker on taint_join (no production call site).
F1 Invariant comments at _RAW_ZONE & modulate, scoped to the @trusted/body==declared firing domain.
F6 Fix stale "merges keep taint_join" comments.
F4 Document the wrong-predicate-validator known boundary.
New authoritative docs/concepts/taint-algebra.md.
Invariant-enforcement tests (closure + rank-invariant + pipeline-level).
Fault-injection tests for the defensive propagation branches (monotonicity / post-assertion).

Release: 0.2.1 (hardening + docs; no user-facing feature, no breaking change).

How it was built

Executor subagent implemented → adversarial reviewer subagent vetted (mutation-tested the new tests, confirmed the F5 INTEGRAL round-trip trap was handled) → returned SHIP-WITH-FIXES with 2 minor doc-only findings, both applied.

Verification

  • Full suite 962 passed, 2 deselected (live clarion_e2e)
  • ruff clean · mypy clean (73 files) · mkdocs build --strict exit 0
  • Soundness oracle battery 30/30 (25 laundering shapes fire PY-WL-101; 5 validated shapes stay clean)
  • Base package stays zero-dep

🤖 Generated with Claude Code

John Morrissey and others added 5 commits May 31, 2026 14:31
…IXED_RAW FP)

Completes the taint_join->least_trusted migration started in wardline-4d94577013
(L2 expression combiners) and wardline-4d9f840c24 (L2 control-flow merges). The
four remaining taint_join call sites — the CALLEE-COMBINATION joins in the L3
call-graph propagation engine — are switched to the rank-meet least_trusted:

  - minimum_scope.py  _refine callee aggregation
  - propagation.py    _compute_scc_round per-round refinement
  - propagation.py    Phase 1 external-influence aggregation
  - propagation.py    Phase 1b multi-source seed-join

Evaluated each site independently (the task was to DECIDE, not assume): all four
are the SAME shape — a function-summary AGGREGATION of the influence of a *set*
of callees into one taint, never a single value built by merging two
provenances. taint_join's MIXED_RAW models a single-value provenance clash,
which has no referent at the function-summary level; the precise single-value
combination (e.g. `return a() + b()`) is already resolved at L2, which itself
uses least_trusted. So a non-anchored function calling two clean-but-different-
family callees (e.g. an ASSURED validator and an INTEGRAL helper) spuriously
became MIXED_RAW (rank 7, in the firing RAW_ZONE); propagated up it fired
PY-WL-101 on clean data — the same FP shape as the L2 merges.

Fail-safe: least_trusted <= taint_join in rank always, so this only ever LOWERS
a combined rank — removes over-flags, never creates under-flags. RAW_ZONE
collapses MIXED_RAW with the other raw states, so a genuinely-raw callee keeps
its rank and still fires; the two operators can only diverge on a firing
decision when least_trusted yields a clean state and taint_join yields MIXED_RAW
(the clean-but-different-family case), which is always the false positive.

taint_join itself stays in core/taints.py (the operator is unchanged); the two
operators remain distinct. Stale docstrings rewritten: propagation.py's
module-header "combination uses taint_join / TRUST_RANK never for combination"
(now false — least_trusted IS a TRUST_RANK-based meet and is the combination
operator) and minimum_scope.py's "MIXED_RAW by design — the conservative
direction" (the exact rationale the L2 commits refuted). Per-site comments pin
the least_trusted choice so the question isn't reopened.

Tests: two buggy-MIXED_RAW assertions corrected to the precise least_trusted
value (test_propagation cyclic + two-anchored-callees; test_analyzer transitive
propagation now UNKNOWN_RAW, floored, not MIXED_RAW); clean-direction +
soundness-companion tests added for the minimum_scope and propagation sites
(two clean-different-family callees stay clean; one raw callee still
propagates). Verified: 936 pytest green, soundness battery 30/30 (no FN),
self-host 0 PY-WL defects, ruff + mypy --strict clean.

Closes wardline-17b9ce2c70

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
L3 callee-combination joins migrate taint_join->least_trusted (MIXED_RAW FP).
Closes wardline-17b9ce2c70.
Follow-up from the 2026-05-31 taint-combination audit (engine found
correct: 0 live FP/FN, battery 30/30). Makes the reachable-set
correctness ENFORCED rather than incidental. Decision: RETAIN the
8-state lattice + taint_join as the documented contrast operator
(ADR docs/decisions/2026-05-31-wardline-taint-lattice-retain.md).

- F5: gate the two ungated TaintState parsers to the reachable subset
  (stdlib rejects INTEGRAL + the unreachable trio; summary_cache keeps
  INTEGRAL, rejects only the trio so trusted-fn caching still works)
- F2: remove the proven-dead unresolved-clamp in the SCC round
- F3: RETAIN marker on taint_join (no production call site)
- F1: invariant comments at _RAW_ZONE & modulate (scoped to the
  @trusted/body==declared firing domain)
- F6: fix stale "merges keep taint_join" comment
- F4: document the wrong-predicate validator blind spot
- New authoritative docs/concepts/taint-algebra.md
- Invariant-enforcement tests (closure + rank-invariant + pipeline)
- Fault-injection tests for the defensive propagation branches

Epic wardline-2b138b3662 (9/10 children; compute_return_callee deferred).
962 tests pass; ruff/mypy/mkdocs --strict clean; oracle battery 30/30.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
.mcp.json holds a machine-specific MCP server path; add it to .gitignore
and untrack it so local edits stay local. File remains on disk.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Hardening + docs release (taint-combination engine first-class hardening,
epic wardline-2b138b3662). No user-facing feature, no breaking change.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Copilot AI review requested due to automatic review settings May 31, 2026 07:57

Copilot AI left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Copilot encountered an error and was unable to review this pull request. You can try again by re-requesting a review.

@tachyon-beep
tachyon-beep merged commit 30cf935 into main May 31, 2026
5 of 6 checks passed
@tachyon-beep
tachyon-beep deleted the taint-combination-hardening branch May 31, 2026 08:01
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants